home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BBS Toolkit
/
BBS Toolkit.iso
/
rbbs_pc
/
rbbsdocs.zip
/
RBBSDOCS.20
< prev
next >
Wrap
Text File
|
1990-11-05
|
21KB
|
426 lines
RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-1
20. RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS
-----------------------------------------------------
RBBS-PC includes a flexible interface for implementing file-transfer
protocols. A "protocol" for the exchange of files is just a set of
cooperative conventions that allow two different computer's software to
transfer files between themselves. RBBS-PC supports four "protocols"
within its own BASIC source code -- ASCII, Xmodem (checksum), Xmodem (CRC),
and 1K-Xmodem. These are totally configurable by the SysOp when setting up
RBBS-PC.
In addition to these four "protocols" and in order to provide advocates of
specific protocols a means of adding their particular flavor of
communications protocol to RBBS-PC, a standard interface has been created
so that "external" protocols can be installed in RBBS-PC. "External"
protocols are simply defined as programs outside of RBBS-PC which perform
the file transfer.
Before calling "external" protocol drivers, RBBS-PC will do the following:
1) verify that the file exists if the file is to be downloaded.
2) for uploads, verify that the file name requested is valid.
3) pass control of the communications port to the external protocol.
RBBS-PC will call the external protocol drivers either via the SHELL
command in BASIC or via a .BAT file.
20.1 Parameters passed to a protocol driver
-------------------------------------------
RBBS-PC detects the installation of external file transfer protocols via an
optional RBBS-PC system file whose default name is PROTO.DEF. If no such
file exists, only internal protocols will be available -- Ascii, Xmodem,
XmodemCRC, 1K-Xmodem. This file may be used to rename or delete some or
all of RBBS-PC's internal protocols. If a PROTO.DEF file exists, all of
RBBS-PC's internal protocols must be specified in it as well. Internal
protocols are NOT automatically included when a PROTO.DEF file exists!
The protocol definition file has thirteen (13) parameters passed for each
external protocol defined for RBBS-PC. Each parameter can be on a separate
line of its own or all parameters can be on a single line (separated by
commas). The parameters passed for each protocol specified are:
Parameter Description
1 Protocol Name
2 Security Level required to use protocol
3 Method to invoke protocol
4 Whether 8 bit connection required
5 Whether "reliable" connection required
6 Whether "batch" mode supported
7 Number of bytes in a block transferred
8 Indicate transfer always successful
9 Factor to estimate file transfer time
10 RBBS-PC "macro" to invoke before protocol
11 Method for checking transfer's success
12 Template to use for downloading
13 Template to use for uploading
Protocol Name -- The FIRST CHARACTER is the letter by which a caller
selects the protocol. The prompt for the selection of protocol includes
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 20-2
the protocol name. It is recommended that the second character be ")" to
resemble the rest of the prompts in RBBS-PC, e.g. "Z)modem". RBBS-PC will
normally put each protocol on the same line, separated by a comma, until
the line gets too long. The SysOp can control the placement of the line by
putting a carriage return line feed at the end of the protocol name. If
this is done, the entire protocol name must be in parentheses. For
example, instead of the prompt
A)scii,X)modem,C)rcXmodem,Y)modem,N)one
a SysOp may want the prompt to be
A)scii (text files only)
X)modem checksum
C)rc Xmodem
Y)modem (1K Xmodem)
N - None (cancel)
Then the protocol definition file , PROTO.DEF, should be constructed using
quotes (to include the carriage return/line feed in the first parameter) as
follows:
"A)scii (text files only)
",...
"X)modem checksum
",...
"C)rc Xmodem
",...
"Y)modem (1K Xmodem)
",...
"N - None (cancel)
",...
with the remaining 12 parameters put where "..." occurs.
Security Level -- This is the minimum security to be able to use the
protocol being described.
Method to Invoke Protocol -- A protocol can be invoked by one of three
methods:
shell,
door, or
internal (S, D, or I).
If "I" is specified, it must be immediately followed by a letter specifying
what internal protocol to use, where the choices are A, X, C, Y, or N
respectively for Ascii, Xmodem, Xmodem CRC, 1K-X(Y)modem, or None (cancel
transfer). "IC" would mean to use RBBS-PC's internal Xmodem CRC. If no
protocol is specified equivalent to the internal "None", RBBS-PC will add
it. If the letter N is used for a transfer protocol, another protocol must
be specified that is equivalent to "None".
Whether to Require 8 Bit -- By putting "8" in this parameter, the SysOp is
specifying that the protocol requires the caller to be able to send or
receive 8 data bits. If 8 data bits is required and the caller is not at 8
bit, RBBS-PC will prompt the caller to change to 8 bit in order to use the
protocol.
RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-3
Whether A Reliable Connection Is Required -- By putting "R" in this
parameter, the SysOp is specifying that the protocol will not be shown or
made available to the caller unless the connections is reliable (i.e. such
as Microcom's MNP protocol that is built into many modems).
Whether Batch is supported -- By putting "B" in this parameter, the SysOp
is indicating that "batch" file transfers are allowed with the protocol.
"Batch" means a multi-file download request will be processed together.
RBBS-PC enters an external protocol only once to do multiple file
downloads. RBBS-PC has been tested with such "batch" protocols as Omen
Technologies' DSZ Zmodem, Megalink, and Sealink.
Blocksize -- This parameter indicates the number of bytes in each block
transferred. This is only used to inform the caller the number of blocks
to expect when downloading. A zero in this parameters will cause RBBS-PC
to report only the number of bytes to expect. For Xmodem or XmodemCRC this
value would be 128. For Ymodem this value would be 1024.
Indicate Transfers Always Successful -- If there is no way for the protocol
to inform RBBS-PC if a transfer was successful, put a "F" in this
parameter, which stands for "Fake" a success report. This means that all
transfers will be regarded as successful.
Zmodem (DSZ) used in a multi-tasking DOS environment (where the DOS
environment variables are shared) and CLINK are examples of protocols that
require this to be set.
Factor to Estimate File Transfer Time -- This is the decimal number used by
RBBS-PC to estimate the elapse time to download a file. The higher the
number, the faster the protocol and the lower the time estimate. Standard
equivalents in RBBS-PC are:
Ascii ......... 0.92
Xmodem ........ 0.78
XmodemCRC ..... 0.78
Kermit ........ 0.78
Ymodem ........ 0.87
Imodem ........ 0.90
YmodemG ....... 0.95
Windowed xmodem 0.78
If no value is specified, a default of 0.87 will be used.
RBBS-PC "Macro" to Invoke Before Protocol -- This is the RBBS-PC "macro"
(i.e. a series of standard RBBS-PC commands) to invoke before invoking the
protocol. It can be used to display special messages, to delay the start
of the protocol, or to prompt for special information passed to the
protocol.
Method for Checking Transfer's Success -- This is required only for
external protocols. This parameter indicates how RBBS-PC is to detect a
file transfer's failure. The format is "x=y=z" where:
x is which parameter tells whether the transfer was successful,
y is the string which indicates failure, and
z is an optional parameter telling RBBS-PC whether to write out
information needed when DOORing to a protocol in advance of the
file exchange.
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 20-4
For QMXFER.EXE from John Friel and the Forbin Project, this would be "4=F"
- meaning the 4th parameter indicates failure if it begins with "F".
For Zmodem as implemented in DSZ from Omen Technologies, the proper choice
depends on whether SHELLing or DOORing is used. For SHELLing, put in
"1=E" to indicate that the first parameter uses "E" to indicate an error
has occurred. For DOORing, put in "4=E=A" to indicate that the fourth
parameter uses "E" when an error has occurred. The "=A" means that RBBS-PC
is to do an advance write of the filename and protocol used. DSZ then
appends its error report to the log file. To the file "XFER-" plus node #
plus ".DEF" RBBS-PC will write out a line containing "<filename>,,<protocol
letter>". Omitting an "=" causes a default to "4=F". The file checked is
"XFER-" plus the node number plus the extension "DEF". On node 1 the file
checked is "XFER-1.DEF".
Template to Use for Downloading -- This is required only for external
protocols. It tells RBBS-PC how to invoke a download. See section 20.2.
Template to Use for Uploading -- This is required only for external
protocols. It tells RBBS-PC how to invoke an upload.
20.2 Calling external protocols using "templates"
-------------------------------------------------
A "template" is used to inform RBBS-PC how to invoke an external protocol.
The first word of the template must be the file name (including file
extension) of the program to invoke. RBBS-PC will check to make sure that
the file exists. If the file does not exist, the protocol will not be made
available to the caller.
RBBS-PC will dynamically substitute values for pre-defined strings inside a
"template". Each supported string is enclosed in square brackets. The
strings supported include:
[n] where n is a positive integer. Substitutes value in a work array
Macros can store the prompted values in specific elements in the
array.
[FILE] Name of the file (FILE.NAME$) to be transferred.
[BAUD] Baud rate. Speed at which the caller dialed RBBS-PC.
[PARITY] Parity used by the caller.
[PORT] DOS device name for the communications port to be used for the
file transfer (COM1,COM2, etc.).
[PORT#] Number of the communications port to be used for the file
transfer (1,2,3, etc.).
[NODE] Number of the RBBS-PC node invoking the file transfer (1,2,3,
etc.).
[PROTO] Letter of the protocol for the file transfer.
Everything else in a template will be passed intact. If the external file
transfer is to be invoked via a SHELL, it is recommended that the external
file transfer program be SHELLed to directly. If the external file
transfer is to be invoked via a DOOR, it can be either
RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-5
1) DOORed to directly using the same template as for SHELLing, or
2) DOORed to indirectly via a .BAT file with the command parameters
passed to it by RBBS-PC. For example, a "door" for QMXFER might have
a download template of:
"RBBSQM.BAT [FILE] [PORT] [BAUD] [PROTO]"
and the file RBBSQM.BAT have the following in it:
C:QMXFER.COM -s -f %1 -l %2 -c -b %3 -p %4
DOS substitutes the passed parameters for the variables beginning with the
percent sign. .BAT files are needed if additional programs to run before
or after the actual file transfer.
The following examples should provide some help in understanding how to
invoke external protocols:
Example #1:
Z)ippy,5,S,8,,,,,0.98,,,"c:\utl\zippy -s [FILE]","c:\utl\zippy -r [FILE]"
Can be interpreted to be:
used "Z" as invoking letter,
put "Z)ippy" in the prompt,
the minimum security to use this protocol is 5,
the protocol will be invoked via a SHELL command,
an 8-bit connection is required,
estimate the download time as 0.98 times as fast as normal,
use normal RBBS-PC type of report to check for a successful transfer,
invoke the protocol for downloads using the following string:
"c:\utl\zippy -s [FILE]"
and invoke the protocol for uploads using the following string:
"c:\utl\zmodem -r [FILE]"
where the file name is substituted for "[FILE]" in either case.
Example #2:
X)modem,5,IX,8,,,128,,0.8,,,,
Can be interpreted to be:
used "X" as invoking letter,
put "X)modem" in the prompt,
the minimum security to use this protocol is 5,
the protocol is an internal RBBS-PC protocol,
an 8-bit connection is required, and
estimate the download time as 0.8 times as fast as normal.
20.3 Parameters Returned by a Protocol Driver
---------------------------------------------
All protocol drivers are expected to return information about the file
transfer in a file named XFER-xx.DEF where the value for xx is the node ID
(1 to 36). If the protocol cannot accommodate this minimal requirement, it
can still be used by telling RBBS-PC to indicate file transfers are always
successful -- section 20.1, parameter 8.
The one item of information RBBS-PC requires to be returned from an
external protocol drive is whether or not the file transfer was successful.
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 20-6
The failure indicator MUST BE the first character of any specified
parameter in the file XFER-xx.DEF. To show that file transfer failures are
indicated by the first parameter and the letter "E" in the file
XFER-xx.DEF, parameter 11 (as described in section 20.1) would be written
as "1=E". To show that file transfer failures are indicated by the fourth
parameter and the letter "F", parameter 11 (as described in section 20.1)
would be written as "4=F".
No other information is required when SHELLing to external file transfer
protocols. However, when DOORing to external file transfer protocols the
log file for the transfer MUST HAVE the file name as the first parameter.
Protocol drivers that do not have the file name as the first parameter can
still be used by telling RBBS-PC to write out three parameters (file name,
an empty parameter, and the letter of the file transfer protocol) before
invoking the external file protocol. This is done by using parameter 11
(as described in section 20.1). As an example, to DOOR to an external file
transfer protocol that indicates a file transfer failure by using the
letter "F" in the fourth parameter, but which does not return the file name
used, parameter 11 (as described in section 20.1) would be written as
"4=F=A". The external protocol would then append its own information to
the log file.
20.4 The Protocol Drivers Tested With RBBS-PC
---------------------------------------------
RBBS-PC has been tested with the following protocol drivers:
CLINK From System Enhancement Associates. Supports batch file
transfers, but requires that transfers always be assumed
successful.
DSZ From Omen Technologies. Supports Ymodem, Ymodem Batch, YmodemG,
and Zmodem. YmodemG requires a "reliable" connection. DSZ logs
the results of the file transfers to a file specified in the
environment variable DSZLOG. Therefore, the AUTOEXEC.BAT file
for an RBBS-PC that uses DSZ should specify
"SET DSZLOG=XFER-x.DEF"
where x is the node number. DSZ seems unable to create a log
file whenever a drive or path is specified. If invoking ZMODEM
via the DOOR mechanism, use the "=A" option at the end of the
success method check so that RBBS-PC will append the information
to the DSZ log it needs and DSZ will then append the success
report. In a multi-user environment where a different
environment variable for each node can not be specified (i.e. all
nodes must share the same DSZ log file), specify that all
transfers are always successful for protocols handled via DSZ.
MLINK MEGALINK protocol supports batch file transfers but requires that
transfers always be assumed successful.
PC-KERMIT from Columbia University. PCKERMIT.EXE is supplied by The Source
as a public service and consists of sliding window KERMIT
protocol. The development of "windowing" within the KERMIT
architecture (i.e. Super KERMIT) was funded by The Source and
implemented by Larry Jordan and Jan van der Eijk.
RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS 20-7
Columbia University holds the copyright and maintains the Kermit
protocol. Like RBBS-PC, Columbia University allows KERMIT to be
passed along to others and "ask only that profit not be your
goal, credit be given where it is due, and that new material be
sent back to us so that we can maintain a definitive and
comprehensive set of KERMIT implementations".
PCKERMIT.EXE is not a terminal program. It simply implements the
Kermit protocol, including the sliding window extension. It will
work with older "Kermit Classic" implementations as well, via
automatic negotiation between the two Kermit programs.
PCKERMIT.EXE runs as a "one-shot" execution then returns to
RBBS-PC. PCKERMIT does not establish a carrier with a remote
system. The connection is established by RBBS-PC. File
transfers must always be assumed successful.
QMXFER is supplied by The Forbin Project. It supports XMODEM
(checksum), XMODEM (CRC), YMODEM, YMODEMG, and IMODEM. YMODEMG
and IMODEM are designed to work when the link between the two
modems is "error free" (i.e. both modems have the MNP protocol
built in). QMXFER.COM runs as a "one-shot" execution, then
returns to RBBS-PC. QMXFER does not establish a carrier with a
remote system. The connection is established by RBBS-PC. File
transfer failures are indicated by an "F" in the fourth parameter
of the log file returned to RBBS-PC.
WXMODEM is supplied by The Forbin Project, and supports the window XMODEM
protocol designed by Pete Boswell. Like all of RBBS-PC's
protocol drivers, WXMODEM.COM runs as a "one-shot" execution then
returns to RBBS-PC. WXMODEM does not establish a carrier with a
remote system. The connection is established by RBBS-PC. File
transfer failures are indicated by an "F" in the fourth parameter
of the log file returned to RBBS-PC.
Other protocols tested with RBBS-PC include SuperK, Jmodem and Puma.